home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / linux / usb_ch9.h < prev    next >
C/C++ Source or Header  |  2005-10-13  |  11KB  |  386 lines
  1. /*
  2.  * This file holds USB constants and structures that are needed for USB
  3.  * device APIs.  These are used by the USB device model, which is defined
  4.  * in chapter 9 of the USB 2.0 specification.  Linux has several APIs in C
  5.  * that need these:
  6.  *
  7.  * - the master/host side Linux-USB kernel driver API;
  8.  * - the "usbfs" user space API; and
  9.  * - (eventually) a Linux "gadget" slave/device side driver API.
  10.  *
  11.  * USB 2.0 adds an additional "On The Go" (OTG) mode, which lets systems
  12.  * act either as a USB master/host or as a USB slave/device.  That means
  13.  * the master and slave side APIs will benefit from working well together.
  14.  */
  15.  
  16. #ifndef __LINUX_USB_CH9_H
  17. #define __LINUX_USB_CH9_H
  18.  
  19. #include <asm/types.h>        /* __u8 etc */
  20. #include <linux/types.h>    /* __le16 */
  21.  
  22. /*-------------------------------------------------------------------------*/
  23.  
  24. /* CONTROL REQUEST SUPPORT */
  25.  
  26. /*
  27.  * USB directions
  28.  *
  29.  * This bit flag is used in endpoint descriptors' bEndpointAddress field.
  30.  * It's also one of three fields in control requests bRequestType.
  31.  */
  32. #define USB_DIR_OUT            0        /* to device */
  33. #define USB_DIR_IN            0x80        /* to host */
  34.  
  35. /*
  36.  * USB types, the second of three bRequestType fields
  37.  */
  38. #define USB_TYPE_MASK            (0x03 << 5)
  39. #define USB_TYPE_STANDARD        (0x00 << 5)
  40. #define USB_TYPE_CLASS            (0x01 << 5)
  41. #define USB_TYPE_VENDOR            (0x02 << 5)
  42. #define USB_TYPE_RESERVED        (0x03 << 5)
  43.  
  44. /*
  45.  * USB recipients, the third of three bRequestType fields
  46.  */
  47. #define USB_RECIP_MASK            0x1f
  48. #define USB_RECIP_DEVICE        0x00
  49. #define USB_RECIP_INTERFACE        0x01
  50. #define USB_RECIP_ENDPOINT        0x02
  51. #define USB_RECIP_OTHER            0x03
  52.  
  53. /*
  54.  * Standard requests, for the bRequest field of a SETUP packet.
  55.  *
  56.  * These are qualified by the bRequestType field, so that for example
  57.  * TYPE_CLASS or TYPE_VENDOR specific feature flags could be retrieved
  58.  * by a GET_STATUS request.
  59.  */
  60. #define USB_REQ_GET_STATUS        0x00
  61. #define USB_REQ_CLEAR_FEATURE        0x01
  62. #define USB_REQ_SET_FEATURE        0x03
  63. #define USB_REQ_SET_ADDRESS        0x05
  64. #define USB_REQ_GET_DESCRIPTOR        0x06
  65. #define USB_REQ_SET_DESCRIPTOR        0x07
  66. #define USB_REQ_GET_CONFIGURATION    0x08
  67. #define USB_REQ_SET_CONFIGURATION    0x09
  68. #define USB_REQ_GET_INTERFACE        0x0A
  69. #define USB_REQ_SET_INTERFACE        0x0B
  70. #define USB_REQ_SYNCH_FRAME        0x0C
  71.  
  72. /*
  73.  * USB feature flags are written using USB_REQ_{CLEAR,SET}_FEATURE, and
  74.  * are read as a bit array returned by USB_REQ_GET_STATUS.  (So there
  75.  * are at most sixteen features of each type.)
  76.  */
  77. #define USB_DEVICE_SELF_POWERED        0    /* (read only) */
  78. #define USB_DEVICE_REMOTE_WAKEUP    1    /* dev may initiate wakeup */
  79. #define USB_DEVICE_TEST_MODE        2    /* (high speed only) */
  80. #define USB_DEVICE_B_HNP_ENABLE        3    /* dev may initiate HNP */
  81. #define USB_DEVICE_A_HNP_SUPPORT    4    /* RH port supports HNP */
  82. #define USB_DEVICE_A_ALT_HNP_SUPPORT    5    /* other RH port does */
  83. #define USB_DEVICE_DEBUG_MODE        6    /* (special devices only) */
  84.  
  85. #define USB_ENDPOINT_HALT        0    /* IN/OUT will STALL */
  86.  
  87.  
  88. /**
  89.  * struct usb_ctrlrequest - SETUP data for a USB device control request
  90.  * @bRequestType: matches the USB bmRequestType field
  91.  * @bRequest: matches the USB bRequest field
  92.  * @wValue: matches the USB wValue field (le16 byte order)
  93.  * @wIndex: matches the USB wIndex field (le16 byte order)
  94.  * @wLength: matches the USB wLength field (le16 byte order)
  95.  *
  96.  * This structure is used to send control requests to a USB device.  It matches
  97.  * the different fields of the USB 2.0 Spec section 9.3, table 9-2.  See the
  98.  * USB spec for a fuller description of the different fields, and what they are
  99.  * used for.
  100.  *
  101.  * Note that the driver for any interface can issue control requests.
  102.  * For most devices, interfaces don't coordinate with each other, so
  103.  * such requests may be made at any time.
  104.  */
  105. struct usb_ctrlrequest {
  106.     __u8 bRequestType;
  107.     __u8 bRequest;
  108.     __le16 wValue;
  109.     __le16 wIndex;
  110.     __le16 wLength;
  111. } __attribute__ ((packed));
  112.  
  113. /*-------------------------------------------------------------------------*/
  114.  
  115. /*
  116.  * STANDARD DESCRIPTORS ... as returned by GET_DESCRIPTOR, or
  117.  * (rarely) accepted by SET_DESCRIPTOR.
  118.  *
  119.  * Note that all multi-byte values here are encoded in little endian
  120.  * byte order "on the wire".  But when exposed through Linux-USB APIs,
  121.  * they've been converted to cpu byte order.
  122.  */
  123.  
  124. /*
  125.  * Descriptor types ... USB 2.0 spec table 9.5
  126.  */
  127. #define USB_DT_DEVICE            0x01
  128. #define USB_DT_CONFIG            0x02
  129. #define USB_DT_STRING            0x03
  130. #define USB_DT_INTERFACE        0x04
  131. #define USB_DT_ENDPOINT            0x05
  132. #define USB_DT_DEVICE_QUALIFIER        0x06
  133. #define USB_DT_OTHER_SPEED_CONFIG    0x07
  134. #define USB_DT_INTERFACE_POWER        0x08
  135. /* these are from a minor usb 2.0 revision (ECN) */
  136. #define USB_DT_OTG            0x09
  137. #define USB_DT_DEBUG            0x0a
  138. #define USB_DT_INTERFACE_ASSOCIATION    0x0b
  139.  
  140. /* conventional codes for class-specific descriptors */
  141. #define USB_DT_CS_DEVICE        0x21
  142. #define USB_DT_CS_CONFIG        0x22
  143. #define USB_DT_CS_STRING        0x23
  144. #define USB_DT_CS_INTERFACE        0x24
  145. #define USB_DT_CS_ENDPOINT        0x25
  146.  
  147. /* All standard descriptors have these 2 fields at the beginning */
  148. struct usb_descriptor_header {
  149.     __u8  bLength;
  150.     __u8  bDescriptorType;
  151. } __attribute__ ((packed));
  152.  
  153.  
  154. /*-------------------------------------------------------------------------*/
  155.  
  156. /* USB_DT_DEVICE: Device descriptor */
  157. struct usb_device_descriptor {
  158.     __u8  bLength;
  159.     __u8  bDescriptorType;
  160.  
  161.     __le16 bcdUSB;
  162.     __u8  bDeviceClass;
  163.     __u8  bDeviceSubClass;
  164.     __u8  bDeviceProtocol;
  165.     __u8  bMaxPacketSize0;
  166.     __le16 idVendor;
  167.     __le16 idProduct;
  168.     __le16 bcdDevice;
  169.     __u8  iManufacturer;
  170.     __u8  iProduct;
  171.     __u8  iSerialNumber;
  172.     __u8  bNumConfigurations;
  173. } __attribute__ ((packed));
  174.  
  175. #define USB_DT_DEVICE_SIZE        18
  176.  
  177.  
  178. /*
  179.  * Device and/or Interface Class codes
  180.  * as found in bDeviceClass or bInterfaceClass
  181.  * and defined by www.usb.org documents
  182.  */
  183. #define USB_CLASS_PER_INTERFACE        0    /* for DeviceClass */
  184. #define USB_CLASS_AUDIO            1
  185. #define USB_CLASS_COMM            2
  186. #define USB_CLASS_HID            3
  187. #define USB_CLASS_PHYSICAL        5
  188. #define USB_CLASS_STILL_IMAGE        6
  189. #define USB_CLASS_PRINTER        7
  190. #define USB_CLASS_MASS_STORAGE        8
  191. #define USB_CLASS_HUB            9
  192. #define USB_CLASS_CDC_DATA        0x0a
  193. #define USB_CLASS_CSCID            0x0b    /* chip+ smart card */
  194. #define USB_CLASS_CONTENT_SEC        0x0d    /* content security */
  195. #define USB_CLASS_VIDEO            0x0e
  196. #define USB_CLASS_APP_SPEC        0xfe
  197. #define USB_CLASS_VENDOR_SPEC        0xff
  198.  
  199. /*-------------------------------------------------------------------------*/
  200.  
  201. /* USB_DT_CONFIG: Configuration descriptor information.
  202.  *
  203.  * USB_DT_OTHER_SPEED_CONFIG is the same descriptor, except that the
  204.  * descriptor type is different.  Highspeed-capable devices can look
  205.  * different depending on what speed they're currently running.  Only
  206.  * devices with a USB_DT_DEVICE_QUALIFIER have any OTHER_SPEED_CONFIG
  207.  * descriptors.
  208.  */
  209. struct usb_config_descriptor {
  210.     __u8  bLength;
  211.     __u8  bDescriptorType;
  212.  
  213.     __le16 wTotalLength;
  214.     __u8  bNumInterfaces;
  215.     __u8  bConfigurationValue;
  216.     __u8  iConfiguration;
  217.     __u8  bmAttributes;
  218.     __u8  bMaxPower;
  219. } __attribute__ ((packed));
  220.  
  221. #define USB_DT_CONFIG_SIZE        9
  222.  
  223. /* from config descriptor bmAttributes */
  224. #define USB_CONFIG_ATT_ONE        (1 << 7)    /* must be set */
  225. #define USB_CONFIG_ATT_SELFPOWER    (1 << 6)    /* self powered */
  226. #define USB_CONFIG_ATT_WAKEUP        (1 << 5)    /* can wakeup */
  227.  
  228. /*-------------------------------------------------------------------------*/
  229.  
  230. /* USB_DT_STRING: String descriptor */
  231. struct usb_string_descriptor {
  232.     __u8  bLength;
  233.     __u8  bDescriptorType;
  234.  
  235.     __le16 wData[1];        /* UTF-16LE encoded */
  236. } __attribute__ ((packed));
  237.  
  238. /* note that "string" zero is special, it holds language codes that
  239.  * the device supports, not Unicode characters.
  240.  */
  241.  
  242. /*-------------------------------------------------------------------------*/
  243.  
  244. /* USB_DT_INTERFACE: Interface descriptor */
  245. struct usb_interface_descriptor {
  246.     __u8  bLength;
  247.     __u8  bDescriptorType;
  248.  
  249.     __u8  bInterfaceNumber;
  250.     __u8  bAlternateSetting;
  251.     __u8  bNumEndpoints;
  252.     __u8  bInterfaceClass;
  253.     __u8  bInterfaceSubClass;
  254.     __u8  bInterfaceProtocol;
  255.     __u8  iInterface;
  256. } __attribute__ ((packed));
  257.  
  258. #define USB_DT_INTERFACE_SIZE        9
  259.  
  260. /*-------------------------------------------------------------------------*/
  261.  
  262. /* USB_DT_ENDPOINT: Endpoint descriptor */
  263. struct usb_endpoint_descriptor {
  264.     __u8  bLength;
  265.     __u8  bDescriptorType;
  266.  
  267.     __u8  bEndpointAddress;
  268.     __u8  bmAttributes;
  269.     __le16 wMaxPacketSize;
  270.     __u8  bInterval;
  271.  
  272.     // NOTE:  these two are _only_ in audio endpoints.
  273.     // use USB_DT_ENDPOINT*_SIZE in bLength, not sizeof.
  274.     __u8  bRefresh;
  275.     __u8  bSynchAddress;
  276. } __attribute__ ((packed));
  277.  
  278. #define USB_DT_ENDPOINT_SIZE        7
  279. #define USB_DT_ENDPOINT_AUDIO_SIZE    9    /* Audio extension */
  280.  
  281.  
  282. /*
  283.  * Endpoints
  284.  */
  285. #define USB_ENDPOINT_NUMBER_MASK    0x0f    /* in bEndpointAddress */
  286. #define USB_ENDPOINT_DIR_MASK        0x80
  287.  
  288. #define USB_ENDPOINT_XFERTYPE_MASK    0x03    /* in bmAttributes */
  289. #define USB_ENDPOINT_XFER_CONTROL    0
  290. #define USB_ENDPOINT_XFER_ISOC        1
  291. #define USB_ENDPOINT_XFER_BULK        2
  292. #define USB_ENDPOINT_XFER_INT        3
  293.  
  294.  
  295. /*-------------------------------------------------------------------------*/
  296.  
  297. /* USB_DT_DEVICE_QUALIFIER: Device Qualifier descriptor */
  298. struct usb_qualifier_descriptor {
  299.     __u8  bLength;
  300.     __u8  bDescriptorType;
  301.  
  302.     __le16 bcdUSB;
  303.     __u8  bDeviceClass;
  304.     __u8  bDeviceSubClass;
  305.     __u8  bDeviceProtocol;
  306.     __u8  bMaxPacketSize0;
  307.     __u8  bNumConfigurations;
  308.     __u8  bRESERVED;
  309. } __attribute__ ((packed));
  310.  
  311.  
  312. /*-------------------------------------------------------------------------*/
  313.  
  314. /* USB_DT_OTG (from OTG 1.0a supplement) */
  315. struct usb_otg_descriptor {
  316.     __u8  bLength;
  317.     __u8  bDescriptorType;
  318.  
  319.     __u8  bmAttributes;    /* support for HNP, SRP, etc */
  320. } __attribute__ ((packed));
  321.  
  322. /* from usb_otg_descriptor.bmAttributes */
  323. #define USB_OTG_SRP        (1 << 0)
  324. #define USB_OTG_HNP        (1 << 1)    /* swap host/device roles */
  325.  
  326. /*-------------------------------------------------------------------------*/
  327.  
  328. /* USB_DT_DEBUG:  for special highspeed devices, replacing serial console */
  329. struct usb_debug_descriptor {
  330.     __u8  bLength;
  331.     __u8  bDescriptorType;
  332.  
  333.     /* bulk endpoints with 8 byte maxpacket */
  334.     __u8  bDebugInEndpoint;
  335.     __u8  bDebugOutEndpoint;
  336. };
  337.  
  338. /*-------------------------------------------------------------------------*/
  339.  
  340. /* USB_DT_INTERFACE_ASSOCIATION: groups interfaces */
  341. struct usb_interface_assoc_descriptor {
  342.     __u8  bLength;
  343.     __u8  bDescriptorType;
  344.  
  345.     __u8  bFirstInterface;
  346.     __u8  bInterfaceCount;
  347.     __u8  bFunctionClass;
  348.     __u8  bFunctionSubClass;
  349.     __u8  bFunctionProtocol;
  350.     __u8  iFunction;
  351. } __attribute__ ((packed));
  352.  
  353.  
  354. /*-------------------------------------------------------------------------*/
  355.  
  356. /* USB 2.0 defines three speeds, here's how Linux identifies them */
  357.  
  358. enum usb_device_speed {
  359.     USB_SPEED_UNKNOWN = 0,            /* enumerating */
  360.     USB_SPEED_LOW, USB_SPEED_FULL,        /* usb 1.1 */
  361.     USB_SPEED_HIGH                /* usb 2.0 */
  362. };
  363.  
  364. enum usb_device_state {
  365.     /* NOTATTACHED isn't in the USB spec, and this state acts
  366.      * the same as ATTACHED ... but it's clearer this way.
  367.      */
  368.     USB_STATE_NOTATTACHED = 0,
  369.  
  370.     /* the chapter 9 device states */
  371.     USB_STATE_ATTACHED,
  372.     USB_STATE_POWERED,
  373.     USB_STATE_DEFAULT,            /* limited function */
  374.     USB_STATE_ADDRESS,
  375.     USB_STATE_CONFIGURED,            /* most functions */
  376.  
  377.     USB_STATE_SUSPENDED
  378.  
  379.     /* NOTE:  there are actually four different SUSPENDED
  380.      * states, returning to POWERED, DEFAULT, ADDRESS, or
  381.      * CONFIGURED respectively when SOF tokens flow again.
  382.      */
  383. };
  384.  
  385. #endif    /* __LINUX_USB_CH9_H */
  386.